<!DOCTYPE html>
<html lang="en" data-color-mode="auto" data-light-theme="light" data-dark-theme="dark">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>G4F - Requests API Guide</title>
    <link rel="apple-touch-icon" sizes="180x180" href="/dist/img/apple-touch-icon.png">
    <link rel="icon" type="image/png" sizes="32x32" href="/dist/img/favicon-32x32.png">
    <link rel="icon" type="image/png" sizes="16x16" href="/dist/img/favicon-16x16.png">
    <link rel="manifest" href="/dist/img/site.webmanifest">
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/light-74231a1f3bbb.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/dark-8a995f0bacd4.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/primer-primitives-225433424a87.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/primer-b8b91660c29d.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/global-205098e9fedd.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/code-177d21388df8.css" />
    <style>
        :root {
            --colour-1: #000000;
            --colour-2: #ccc;
            --colour-3: #e4d4ff;
            --colour-4: #f0f0f0;
            --colour-5: #181818;
            --colour-6: #242424;
            --accent: #8b3dff;
            --gradient: #1a1a1a;
            --background: #16101b;
            --size: 70vw;
            --top: 50%;
            --blur: 40px;
            --opacity: 0.6;
        }

        /* Body and text color */
        body {
            height: 100vh;
            margin: 0;
            padding: 0;
        }

        .hidden {
            display: none;
        }

        .container-lg {
            margin: 0 auto;
            padding: 8px;
        }

        @media only screen and (min-width: 40em) {
            .container-lg {
                max-width: 84%;
            }
        }
    </style>
</head>
<body>
    <article class="markdown-body entry-content container-lg" itemprop="text"><div class="markdown-heading"><h2 class="heading-element">G4F - Requests API Guide</h2><a id="user-content-g4f---requests-api-guide" class="anchor" aria-label="Permalink: G4F - Requests API Guide" href="#g4f---requests-api-guide"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h2 class="heading-element">Table of Contents</h2><a id="user-content-table-of-contents" class="anchor" aria-label="Permalink: Table of Contents" href="#table-of-contents"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li>
<a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#installing-dependencies">Installing Dependencies</a></li>
</ul>
</li>
<li><a href="#making-api-requests">Making API Requests</a></li>
<li>
<a href="#text-generation">Text Generation</a>
<ul>
<li><a href="#using-the-chat-completions-endpoint">Using the Chat Completions Endpoint</a></li>
<li><a href="#streaming-text-generation">Streaming Text Generation</a></li>
</ul>
</li>
<li>
<a href="#model-retrieval">Model Retrieval</a>
<ul>
<li><a href="#fetching-available-models">Fetching Available Models</a></li>
</ul>
</li>
<li>
<a href="#image-generation">Image Generation</a>
<ul>
<li><a href="#creating-images-with-ai">Creating Images with AI</a></li>
</ul>
</li>
<li><a href="#advanced-usage">Advanced Usage</a></li>
</ul>
<div class="markdown-heading"><h2 class="heading-element">Introduction</h2><a id="user-content-introduction" class="anchor" aria-label="Permalink: Introduction" href="#introduction"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>Welcome to the G4F Requests API Guide, a powerful tool for leveraging AI capabilities directly from your Python applications using HTTP requests. This guide will take you through the steps of setting up requests to interact with AI models for a variety of tasks, from text generation to image creation.</p>
<div class="markdown-heading"><h2 class="heading-element">Getting Started</h2><a id="user-content-getting-started" class="anchor" aria-label="Permalink: Getting Started" href="#getting-started"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Installing Dependencies</h3><a id="user-content-installing-dependencies" class="anchor" aria-label="Permalink: Installing Dependencies" href="#installing-dependencies"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>Ensure you have the <code>requests</code> library installed in your environment. You can install it via <code>pip</code> if needed:</p>
<div class="highlight highlight-source-shell"><pre>pip install requests</pre></div>
<p>This guide provides examples on how to make API requests using Python's <code>requests</code> library, focusing on tasks such as text and image generation, as well as retrieving available models.</p>
<div class="markdown-heading"><h2 class="heading-element">Making API Requests</h2><a id="user-content-making-api-requests" class="anchor" aria-label="Permalink: Making API Requests" href="#making-api-requests"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>Before diving into specific functionalities, it's essential to understand how to structure your API requests. All endpoints assume that your server is running locally at <code>http://localhost</code>. If your server is running on a different port, adjust the URLs accordingly (e.g., <code>http://localhost:8000</code>).</p>
<div class="markdown-heading"><h2 class="heading-element">Text Generation</h2><a id="user-content-text-generation" class="anchor" aria-label="Permalink: Text Generation" href="#text-generation"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Using the Chat Completions Endpoint</h3><a id="user-content-using-the-chat-completions-endpoint" class="anchor" aria-label="Permalink: Using the Chat Completions Endpoint" href="#using-the-chat-completions-endpoint"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>To generate text responses using the chat completions endpoint, follow this example:</p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">requests</span>

<span class="pl-c"># Define the payload</span>
<span class="pl-s1">payload</span> <span class="pl-c1">=</span> {
    <span class="pl-s">"model"</span>: <span class="pl-s">"gpt-4o"</span>,
    <span class="pl-s">"temperature"</span>: <span class="pl-c1">0.9</span>,
    <span class="pl-s">"messages"</span>: [{<span class="pl-s">"role"</span>: <span class="pl-s">"system"</span>, <span class="pl-s">"content"</span>: <span class="pl-s">"Hello, how are you?"</span>}]
}

<span class="pl-c"># Send the POST request to the chat completions endpoint</span>
<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">requests</span>.<span class="pl-c1">post</span>(<span class="pl-s">"http://localhost/v1/chat/completions"</span>, <span class="pl-s1">json</span><span class="pl-c1">=</span><span class="pl-s1">payload</span>)

<span class="pl-c"># Check if the request was successful</span>
<span class="pl-k">if</span> <span class="pl-s1">response</span>.<span class="pl-c1">status_code</span> <span class="pl-c1">==</span> <span class="pl-c1">200</span>:
    <span class="pl-c"># Print the response text</span>
    <span class="pl-en">print</span>(<span class="pl-s1">response</span>.<span class="pl-c1">text</span>)
<span class="pl-k">else</span>:
    <span class="pl-en">print</span>(<span class="pl-s">f"Request failed with status code <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">response</span>.<span class="pl-c1">status_code</span><span class="pl-kos">}</span></span>"</span>)
    <span class="pl-en">print</span>(<span class="pl-s">"Response:"</span>, <span class="pl-s1">response</span>.<span class="pl-c1">text</span>)</pre></div>
<p><strong>Explanation:</strong></p>
<ul>
<li>This request sends a conversation context to the model, which in turn generates and returns a response.</li>
<li>The <code>temperature</code> parameter controls the randomness of the output.</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Streaming Text Generation</h3><a id="user-content-streaming-text-generation" class="anchor" aria-label="Permalink: Streaming Text Generation" href="#streaming-text-generation"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>For scenarios where you want to receive partial responses or stream data as it's generated, you can utilize the streaming capabilities of the API. Here's how you can implement streaming text generation using Python's <code>requests</code> library:</p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">requests</span>
<span class="pl-k">import</span> <span class="pl-s1">json</span>

<span class="pl-k">def</span> <span class="pl-en">fetch_response</span>(<span class="pl-s1">url</span>, <span class="pl-s1">model</span>, <span class="pl-s1">messages</span>):
    <span class="pl-s">"""</span>
<span class="pl-s">    Sends a POST request to the streaming chat completions endpoint.</span>
<span class="pl-s"></span>
<span class="pl-s">    Args:</span>
<span class="pl-s">        url (str): The API endpoint URL.</span>
<span class="pl-s">        model (str): The model to use for text generation.</span>
<span class="pl-s">        messages (list): A list of message dictionaries.</span>
<span class="pl-s"></span>
<span class="pl-s">    Returns:</span>
<span class="pl-s">        requests.Response: The streamed response object.</span>
<span class="pl-s">    """</span>
    <span class="pl-s1">payload</span> <span class="pl-c1">=</span> {<span class="pl-s">"model"</span>: <span class="pl-s1">model</span>, <span class="pl-s">"messages"</span>: <span class="pl-s1">messages</span>, <span class="pl-s">"stream"</span>: <span class="pl-c1">True</span>}
    <span class="pl-s1">headers</span> <span class="pl-c1">=</span> {
        <span class="pl-s">"Content-Type"</span>: <span class="pl-s">"application/json"</span>,
        <span class="pl-s">"Accept"</span>: <span class="pl-s">"text/event-stream"</span>,
    }
    <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">requests</span>.<span class="pl-c1">post</span>(<span class="pl-s1">url</span>, <span class="pl-s1">headers</span><span class="pl-c1">=</span><span class="pl-s1">headers</span>, <span class="pl-s1">json</span><span class="pl-c1">=</span><span class="pl-s1">payload</span>, <span class="pl-s1">stream</span><span class="pl-c1">=</span><span class="pl-c1">True</span>)
    <span class="pl-k">if</span> <span class="pl-s1">response</span>.<span class="pl-c1">status_code</span> <span class="pl-c1">!=</span> <span class="pl-c1">200</span>:
        <span class="pl-k">raise</span> <span class="pl-en">Exception</span>(
            <span class="pl-s">f"Failed to send message: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">response</span>.<span class="pl-c1">status_code</span><span class="pl-kos">}</span></span> <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">response</span>.<span class="pl-c1">text</span><span class="pl-kos">}</span></span>"</span>
        )
    <span class="pl-k">return</span> <span class="pl-s1">response</span>

<span class="pl-k">def</span> <span class="pl-en">process_stream</span>(<span class="pl-s1">response</span>):
    <span class="pl-s">"""</span>
<span class="pl-s">    Processes the streamed response and extracts messages.</span>
<span class="pl-s"></span>
<span class="pl-s">    Args:</span>
<span class="pl-s">        response (requests.Response): The streamed response object.</span>
<span class="pl-s">        output_queue (Queue): A queue to store the extracted messages.</span>
<span class="pl-s">    """</span>
    <span class="pl-k">for</span> <span class="pl-s1">line</span> <span class="pl-c1">in</span> <span class="pl-s1">response</span>.<span class="pl-c1">iter_lines</span>():
        <span class="pl-k">if</span> <span class="pl-s1">line</span>:
            <span class="pl-s1">line</span> <span class="pl-c1">=</span> <span class="pl-s1">line</span>.<span class="pl-c1">decode</span>(<span class="pl-s">"utf-8"</span>)
            <span class="pl-k">if</span> <span class="pl-s1">line</span> <span class="pl-c1">==</span> <span class="pl-s">"data: [DONE]"</span>:
                <span class="pl-en">print</span>(<span class="pl-s">"<span class="pl-cce">\n</span><span class="pl-cce">\n</span>Conversation completed."</span>)
                <span class="pl-k">break</span>
            <span class="pl-k">if</span> <span class="pl-s1">line</span>.<span class="pl-c1">startswith</span>(<span class="pl-s">"data: "</span>):
                <span class="pl-k">try</span>:
                    <span class="pl-s1">data</span> <span class="pl-c1">=</span> <span class="pl-s1">json</span>.<span class="pl-c1">loads</span>(<span class="pl-s1">line</span>[<span class="pl-c1">6</span>:])
                    <span class="pl-s1">message</span> <span class="pl-c1">=</span> <span class="pl-s1">data</span>.<span class="pl-c1">get</span>(<span class="pl-s">"choices"</span>, [{}])[<span class="pl-c1">0</span>].<span class="pl-c1">get</span>(<span class="pl-s">"delta"</span>, {}).<span class="pl-c1">get</span>(<span class="pl-s">"content"</span>)
                    <span class="pl-k">if</span> <span class="pl-s1">message</span>:
                        <span class="pl-en">print</span>(<span class="pl-s1">message</span>, <span class="pl-s1">end</span><span class="pl-c1">=</span><span class="pl-s">""</span>, <span class="pl-s1">flush</span><span class="pl-c1">=</span><span class="pl-c1">True</span>)
                <span class="pl-k">except</span> <span class="pl-s1">json</span>.<span class="pl-c1">JSONDecodeError</span> <span class="pl-k">as</span> <span class="pl-s1">e</span>:
                    <span class="pl-en">print</span>(<span class="pl-s">f"Error decoding JSON: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">e</span><span class="pl-kos">}</span></span>"</span>)
                    <span class="pl-k">continue</span>

<span class="pl-c"># Define the API endpoint</span>
<span class="pl-s1">chat_url</span> <span class="pl-c1">=</span> <span class="pl-s">"http://localhost:8080/v1/chat/completions"</span>

<span class="pl-c"># Define the payload</span>
<span class="pl-s1">model</span> <span class="pl-c1">=</span> <span class="pl-s">""</span>
<span class="pl-s1">messages</span> <span class="pl-c1">=</span> [{<span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>, <span class="pl-s">"content"</span>: <span class="pl-s">"Hello, how are you?"</span>}]

<span class="pl-k">try</span>:
    <span class="pl-c"># Fetch the streamed response</span>
    <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-en">fetch_response</span>(<span class="pl-s1">chat_url</span>, <span class="pl-s1">model</span>, <span class="pl-s1">messages</span>)
    
    <span class="pl-c"># Process the streamed response</span>
    <span class="pl-en">process_stream</span>(<span class="pl-s1">response</span>)

<span class="pl-k">except</span> <span class="pl-v">Exception</span> <span class="pl-k">as</span> <span class="pl-s1">e</span>:
    <span class="pl-en">print</span>(<span class="pl-s">f"An error occurred: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">e</span><span class="pl-kos">}</span></span>"</span>)</pre></div>
<p><strong>Explanation:</strong></p>
<ul>
<li>
<p><strong><code>fetch_response</code> Function:</strong></p>
<ul>
<li>Sends a POST request to the streaming chat completions endpoint with the specified model and messages.</li>
<li>Sets <code>stream</code> parameter to <code>true</code> to enable streaming.</li>
<li>Raises an exception if the request fails.</li>
</ul>
</li>
<li>
<p><strong><code>process_stream</code> Function:</strong></p>
<ul>
<li>Iterates over each line in the streamed response.</li>
<li>Decodes the line and checks for the termination signal <code>"data: [DONE]"</code>.</li>
<li>Parses lines that start with <code>"data: "</code> to extract the message content.</li>
</ul>
</li>
<li>
<p><strong>Main Execution:</strong></p>
<ul>
<li>Defines the API endpoint, model, and messages.</li>
<li>Fetches and processes the streamed response.</li>
<li>Retrieves and prints messages.</li>
</ul>
</li>
</ul>
<p><strong>Usage Tips:</strong></p>
<ul>
<li>Ensure your local server supports streaming.</li>
<li>Adjust the <code>chat_url</code> if your local server runs on a different port or path.</li>
<li>Use threading or asynchronous programming for handling streams in real-time applications.</li>
</ul>
<div class="markdown-heading"><h2 class="heading-element">Model Retrieval</h2><a id="user-content-model-retrieval" class="anchor" aria-label="Permalink: Model Retrieval" href="#model-retrieval"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Fetching Available Models</h3><a id="user-content-fetching-available-models" class="anchor" aria-label="Permalink: Fetching Available Models" href="#fetching-available-models"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>To retrieve a list of available models, you can use the following function:</p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">requests</span>

<span class="pl-k">def</span> <span class="pl-en">fetch_models</span>():
    <span class="pl-s">"""</span>
<span class="pl-s">    Retrieves the list of available models from the API.</span>
<span class="pl-s"></span>
<span class="pl-s">    Returns:</span>
<span class="pl-s">        dict: A dictionary containing available models or an error message.</span>
<span class="pl-s">    """</span>
    <span class="pl-s1">url</span> <span class="pl-c1">=</span> <span class="pl-s">"http://localhost/v1/models/"</span>
    <span class="pl-k">try</span>:
        <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">requests</span>.<span class="pl-c1">get</span>(<span class="pl-s1">url</span>)
        <span class="pl-s1">response</span>.<span class="pl-c1">raise_for_status</span>()  <span class="pl-c"># Raise an error for HTTP issues</span>
        <span class="pl-k">return</span> <span class="pl-s1">response</span>.<span class="pl-c1">json</span>()  <span class="pl-c"># Parse and return the JSON response</span>
    <span class="pl-k">except</span> <span class="pl-v">Exception</span> <span class="pl-k">as</span> <span class="pl-s1">e</span>:
        <span class="pl-k">return</span> {<span class="pl-s">"error"</span>: <span class="pl-en">str</span>(<span class="pl-s1">e</span>)}  <span class="pl-c"># Return an error message if something goes wrong</span>

<span class="pl-s1">models</span> <span class="pl-c1">=</span> <span class="pl-en">fetch_models</span>()

<span class="pl-en">print</span>(<span class="pl-s1">models</span>)</pre></div>
<p><strong>Explanation:</strong></p>
<ul>
<li>The <code>fetch_models</code> function makes a GET request to the models endpoint.</li>
<li>It handles HTTP errors and returns a parsed JSON response containing available models or an error message.</li>
</ul>
<div class="markdown-heading"><h2 class="heading-element">Image Generation</h2><a id="user-content-image-generation" class="anchor" aria-label="Permalink: Image Generation" href="#image-generation"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Creating Images with AI</h3><a id="user-content-creating-images-with-ai" class="anchor" aria-label="Permalink: Creating Images with AI" href="#creating-images-with-ai"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>The following function demonstrates how to generate images using a specified model:</p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">requests</span>

<span class="pl-k">def</span> <span class="pl-en">generate_image</span>(<span class="pl-s1">prompt</span>: <span class="pl-smi">str</span>, <span class="pl-s1">model</span>: <span class="pl-smi">str</span> <span class="pl-c1">=</span> <span class="pl-s">"flux-4o"</span>):
    <span class="pl-s">"""</span>
<span class="pl-s">    Generates an image based on the provided text prompt.</span>
<span class="pl-s"></span>
<span class="pl-s">    Args:</span>
<span class="pl-s">        prompt (str): The text prompt for image generation.</span>
<span class="pl-s">        model (str, optional): The model to use for image generation. Defaults to "flux-4o".</span>
<span class="pl-s"></span>
<span class="pl-s">    Returns:</span>
<span class="pl-s">        tuple: A tuple containing the image URL, caption, and the full response.</span>
<span class="pl-s">    """</span>
    <span class="pl-s1">payload</span> <span class="pl-c1">=</span> {
        <span class="pl-s">"model"</span>: <span class="pl-s1">model</span>,
        <span class="pl-s">"temperature"</span>: <span class="pl-c1">0.9</span>,
        <span class="pl-s">"prompt"</span>: <span class="pl-s1">prompt</span>.<span class="pl-c1">replace</span>(<span class="pl-s">" "</span>, <span class="pl-s">"+"</span>),
    }

    <span class="pl-k">try</span>:
        <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">requests</span>.<span class="pl-c1">post</span>(<span class="pl-s">"http://localhost/v1/images/generate"</span>, <span class="pl-s1">json</span><span class="pl-c1">=</span><span class="pl-s1">payload</span>)
        <span class="pl-s1">response</span>.<span class="pl-c1">raise_for_status</span>()
        <span class="pl-s1">res</span> <span class="pl-c1">=</span> <span class="pl-s1">response</span>.<span class="pl-c1">json</span>()

        <span class="pl-s1">data</span> <span class="pl-c1">=</span> <span class="pl-s1">res</span>.<span class="pl-c1">get</span>(<span class="pl-s">"data"</span>)
        <span class="pl-k">if</span> <span class="pl-c1">not</span> <span class="pl-s1">data</span> <span class="pl-c1">or</span> <span class="pl-c1">not</span> <span class="pl-en">isinstance</span>(<span class="pl-s1">data</span>, <span class="pl-s1">list</span>):
            <span class="pl-k">raise</span> <span class="pl-en">ValueError</span>(<span class="pl-s">"Invalid 'data' in response"</span>)

        <span class="pl-s1">image_url</span> <span class="pl-c1">=</span> <span class="pl-s1">data</span>[<span class="pl-c1">0</span>].<span class="pl-c1">get</span>(<span class="pl-s">"url"</span>)
        <span class="pl-k">if</span> <span class="pl-c1">not</span> <span class="pl-s1">image_url</span>:
            <span class="pl-k">raise</span> <span class="pl-en">ValueError</span>(<span class="pl-s">"No 'url' found in response data"</span>)

        <span class="pl-s1">timestamp</span> <span class="pl-c1">=</span> <span class="pl-s1">res</span>.<span class="pl-c1">get</span>(<span class="pl-s">"created"</span>)
        <span class="pl-s1">caption</span> <span class="pl-c1">=</span> <span class="pl-s">f"Prompt: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">prompt</span><span class="pl-kos">}</span></span><span class="pl-cce">\n</span>Created: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">timestamp</span><span class="pl-kos">}</span></span><span class="pl-cce">\n</span>Model: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">model</span><span class="pl-kos">}</span></span>"</span>
        <span class="pl-k">return</span> <span class="pl-s1">image_url</span>, <span class="pl-s1">caption</span>, <span class="pl-s1">res</span>

    <span class="pl-k">except</span> <span class="pl-v">Exception</span> <span class="pl-k">as</span> <span class="pl-s1">e</span>:
        <span class="pl-k">return</span> <span class="pl-c1">None</span>, <span class="pl-s">f"Error: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">e</span><span class="pl-kos">}</span></span>"</span>, <span class="pl-c1">None</span>

<span class="pl-s1">prompt</span> <span class="pl-c1">=</span> <span class="pl-s">"A tiger in a forest"</span>

<span class="pl-s1">image_url</span>, <span class="pl-s1">caption</span>, <span class="pl-s1">res</span> <span class="pl-c1">=</span> <span class="pl-en">generate_image</span>(<span class="pl-s1">prompt</span>)

<span class="pl-en">print</span>(<span class="pl-s">"API Response:"</span>, <span class="pl-s1">res</span>)
<span class="pl-en">print</span>(<span class="pl-s">"Image URL:"</span>, <span class="pl-s1">image_url</span>)
<span class="pl-en">print</span>(<span class="pl-s">"Caption:"</span>, <span class="pl-s1">caption</span>)</pre></div>
<p><strong>Explanation:</strong></p>
<ul>
<li>The <code>generate_image</code> function constructs a request to create an image based on a text prompt.</li>
<li>It handles responses and possible errors, ensuring a URL and caption are returned if successful.</li>
</ul>
<div class="markdown-heading"><h2 class="heading-element">Advanced Usage</h2><a id="user-content-advanced-usage" class="anchor" aria-label="Permalink: Advanced Usage" href="#advanced-usage"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>This guide has demonstrated basic usage scenarios for the G4F Requests API. The API provides robust capabilities for integrating advanced AI into your applications. You can expand upon these examples to fit more complex workflows and tasks, ensuring your applications are built with cutting-edge AI features.</p>
<div class="markdown-heading"><h3 class="heading-element">Handling Concurrency and Asynchronous Requests</h3><a id="user-content-handling-concurrency-and-asynchronous-requests" class="anchor" aria-label="Permalink: Handling Concurrency and Asynchronous Requests" href="#handling-concurrency-and-asynchronous-requests"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>For applications requiring high performance and non-blocking operations, consider using asynchronous programming libraries such as <code>aiohttp</code> or <code>httpx</code>. Here's an example using <code>aiohttp</code>:</p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">aiohttp</span>
<span class="pl-k">import</span> <span class="pl-s1">asyncio</span>
<span class="pl-k">import</span> <span class="pl-s1">json</span>
<span class="pl-k">from</span> <span class="pl-s1">queue</span> <span class="pl-k">import</span> <span class="pl-v">Queue</span>

<span class="pl-k">async</span> <span class="pl-k">def</span> <span class="pl-en">fetch_response_async</span>(<span class="pl-s1">url</span>, <span class="pl-s1">model</span>, <span class="pl-s1">messages</span>, <span class="pl-s1">output_queue</span>):
    <span class="pl-s">"""</span>
<span class="pl-s">    Asynchronously sends a POST request to the streaming chat completions endpoint and processes the stream.</span>
<span class="pl-s"></span>
<span class="pl-s">    Args:</span>
<span class="pl-s">        url (str): The API endpoint URL.</span>
<span class="pl-s">        model (str): The model to use for text generation.</span>
<span class="pl-s">        messages (list): A list of message dictionaries.</span>
<span class="pl-s">        output_queue (Queue): A queue to store the extracted messages.</span>
<span class="pl-s">    """</span>
    <span class="pl-s1">payload</span> <span class="pl-c1">=</span> {<span class="pl-s">"model"</span>: <span class="pl-s1">model</span>, <span class="pl-s">"messages"</span>: <span class="pl-s1">messages</span>, <span class="pl-s">"stream"</span>: <span class="pl-c1">True</span>}
    <span class="pl-s1">headers</span> <span class="pl-c1">=</span> {
        <span class="pl-s">"Content-Type"</span>: <span class="pl-s">"application/json"</span>,
        <span class="pl-s">"Accept"</span>: <span class="pl-s">"text/event-stream"</span>,
    }

    <span class="pl-k">async</span> <span class="pl-k">with</span> <span class="pl-s1">aiohttp</span>.<span class="pl-c1">ClientSession</span>() <span class="pl-k">as</span> <span class="pl-s1">session</span>:
        <span class="pl-k">async</span> <span class="pl-k">with</span> <span class="pl-s1">session</span>.<span class="pl-c1">post</span>(<span class="pl-s1">url</span>, <span class="pl-s1">headers</span><span class="pl-c1">=</span><span class="pl-s1">headers</span>, <span class="pl-s1">json</span><span class="pl-c1">=</span><span class="pl-s1">payload</span>) <span class="pl-k">as</span> <span class="pl-s1">resp</span>:
            <span class="pl-k">if</span> <span class="pl-s1">resp</span>.<span class="pl-c1">status</span> <span class="pl-c1">!=</span> <span class="pl-c1">200</span>:
                <span class="pl-s1">text</span> <span class="pl-c1">=</span> <span class="pl-k">await</span> <span class="pl-s1">resp</span>.<span class="pl-c1">text</span>()
                <span class="pl-k">raise</span> <span class="pl-en">Exception</span>(<span class="pl-s">f"Failed to send message: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">resp</span>.<span class="pl-c1">status</span><span class="pl-kos">}</span></span> <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">text</span><span class="pl-kos">}</span></span>"</span>)
            
            <span class="pl-k">async</span> <span class="pl-k">for</span> <span class="pl-s1">line</span> <span class="pl-c1">in</span> <span class="pl-s1">resp</span>.<span class="pl-c1">content</span>:
                <span class="pl-s1">decoded_line</span> <span class="pl-c1">=</span> <span class="pl-s1">line</span>.<span class="pl-c1">decode</span>(<span class="pl-s">'utf-8'</span>).<span class="pl-c1">strip</span>()
                <span class="pl-k">if</span> <span class="pl-s1">decoded_line</span> <span class="pl-c1">==</span> <span class="pl-s">"data: [DONE]"</span>:
                    <span class="pl-k">break</span>
                <span class="pl-k">if</span> <span class="pl-s1">decoded_line</span>.<span class="pl-c1">startswith</span>(<span class="pl-s">"data: "</span>):
                    <span class="pl-k">try</span>:
                        <span class="pl-s1">data</span> <span class="pl-c1">=</span> <span class="pl-s1">json</span>.<span class="pl-c1">loads</span>(<span class="pl-s1">decoded_line</span>[<span class="pl-c1">6</span>:])
                        <span class="pl-s1">message</span> <span class="pl-c1">=</span> <span class="pl-s1">data</span>.<span class="pl-c1">get</span>(<span class="pl-s">"choices"</span>, [{}])[<span class="pl-c1">0</span>].<span class="pl-c1">get</span>(<span class="pl-s">"delta"</span>, {}).<span class="pl-c1">get</span>(<span class="pl-s">"content"</span>)
                        <span class="pl-k">if</span> <span class="pl-s1">message</span>:
                            <span class="pl-s1">output_queue</span>.<span class="pl-c1">put</span>(<span class="pl-s1">message</span>)
                    <span class="pl-k">except</span> <span class="pl-s1">json</span>.<span class="pl-c1">JSONDecodeError</span>:
                        <span class="pl-k">continue</span>

<span class="pl-k">async</span> <span class="pl-k">def</span> <span class="pl-en">main</span>():
    <span class="pl-s1">chat_url</span> <span class="pl-c1">=</span> <span class="pl-s">"http://localhost/v1/chat/completions"</span>
    <span class="pl-s1">model</span> <span class="pl-c1">=</span> <span class="pl-s">"gpt-4o"</span>
    <span class="pl-s1">messages</span> <span class="pl-c1">=</span> [{<span class="pl-s">"role"</span>: <span class="pl-s">"system"</span>, <span class="pl-s">"content"</span>: <span class="pl-s">"Hello, how are you?"</span>}]
    <span class="pl-s1">output_queue</span> <span class="pl-c1">=</span> <span class="pl-en">Queue</span>()

    <span class="pl-k">try</span>:
        <span class="pl-k">await</span> <span class="pl-en">fetch_response_async</span>(<span class="pl-s1">chat_url</span>, <span class="pl-s1">model</span>, <span class="pl-s1">messages</span>, <span class="pl-s1">output_queue</span>)
        
        <span class="pl-k">while</span> <span class="pl-c1">not</span> <span class="pl-s1">output_queue</span>.<span class="pl-c1">empty</span>():
            <span class="pl-s1">msg</span> <span class="pl-c1">=</span> <span class="pl-s1">output_queue</span>.<span class="pl-c1">get</span>()
            <span class="pl-en">print</span>(<span class="pl-s1">msg</span>)

    <span class="pl-k">except</span> <span class="pl-v">Exception</span> <span class="pl-k">as</span> <span class="pl-s1">e</span>:
        <span class="pl-en">print</span>(<span class="pl-s">f"An error occurred: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">e</span><span class="pl-kos">}</span></span>"</span>)

<span class="pl-c"># Run the asynchronous main function</span>
<span class="pl-s1">asyncio</span>.<span class="pl-c1">run</span>(<span class="pl-en">main</span>())</pre></div>
<p><strong>Explanation:</strong></p>
<ul>
<li>
<strong><code>aiohttp</code> Library:</strong> Facilitates asynchronous HTTP requests, allowing your application to handle multiple requests concurrently without blocking.</li>
<li>
<strong><code>fetch_response_async</code> Function:</strong>
<ul>
<li>Sends an asynchronous POST request to the streaming chat completions endpoint.</li>
<li>Processes the streamed response line by line.</li>
<li>Extracts messages and enqueues them into <code>output_queue</code>.</li>
</ul>
</li>
<li>
<strong><code>main</code> Function:</strong>
<ul>
<li>Defines the API endpoint, model, and messages.</li>
<li>Initializes a <code>Queue</code> to store incoming messages.</li>
<li>Invokes the asynchronous fetch function and processes the messages.</li>
</ul>
</li>
</ul>
<p><strong>Benefits:</strong></p>
<ul>
<li>
<strong>Performance:</strong> Handles multiple requests efficiently, reducing latency in high-throughput applications.</li>
<li>
<strong>Scalability:</strong> Easily scales with increasing demand, making it suitable for production environments.</li>
</ul>
<p><strong>Note:</strong> Ensure you have <code>aiohttp</code> installed:</p>
<div class="highlight highlight-source-shell"><pre>pip install aiohttp</pre></div>
<div class="markdown-heading"><h2 class="heading-element">Conclusion</h2><a id="user-content-conclusion" class="anchor" aria-label="Permalink: Conclusion" href="#conclusion"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>By following this guide, you can effectively integrate the G4F Requests API into your Python applications, enabling powerful AI-driven functionalities such as text and image generation, model retrieval, and handling streaming data. Whether you're building simple scripts or complex, high-performance applications, the examples provided offer a solid foundation to harness the full potential of AI in your projects.</p>
<p>Feel free to customize and expand upon these examples to suit your specific needs. If you encounter any issues or have further questions, don't hesitate to seek assistance or refer to additional resources.</p>
<hr>
<div class="markdown-heading"><h1 class="heading-element">Additional Notes</h1><a id="user-content-additional-notes" class="anchor" aria-label="Permalink: Additional Notes" href="#additional-notes"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<ol>
<li>
<p><strong>Adjusting the Base URL:</strong></p>
<ul>
<li>The guide assumes your API server is accessible at <code>http://localhost</code>. If your server runs on a different port (e.g., <code>8000</code>), update the URLs accordingly:
<div class="highlight highlight-source-python"><pre><span class="pl-c"># Example for port 8000</span>
<span class="pl-s1">chat_url</span> <span class="pl-c1">=</span> <span class="pl-s">"http://localhost:8000/v1/chat/completions"</span></pre></div>
</li>
</ul>
</li>
<li>
<p><strong>Environment Variables (Optional):</strong></p>
<ul>
<li>For better flexibility and security, consider using environment variables to store your base URL and other sensitive information.
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">os</span>

<span class="pl-c1">BASE_URL</span> <span class="pl-c1">=</span> <span class="pl-s1">os</span>.<span class="pl-c1">getenv</span>(<span class="pl-s">"API_BASE_URL"</span>, <span class="pl-s">"http://localhost"</span>)
<span class="pl-s1">chat_url</span> <span class="pl-c1">=</span> <span class="pl-s">f"<span class="pl-s1"><span class="pl-kos">{</span><span class="pl-c1">BASE_URL</span><span class="pl-kos">}</span></span>/v1/chat/completions"</span></pre></div>
</li>
</ul>
</li>
<li>
<p><strong>Error Handling:</strong></p>
<ul>
<li>Always implement robust error handling to gracefully manage unexpected scenarios, such as network failures or invalid responses.</li>
</ul>
</li>
<li>
<p><strong>Security Considerations:</strong></p>
<ul>
<li>Ensure that your local API server is secured, especially if accessible over a network. Implement authentication mechanisms if necessary.</li>
</ul>
</li>
<li>
<p><strong>Testing:</strong></p>
<ul>
<li>Utilize tools like <a href="https://www.postman.com/" rel="nofollow">Postman</a> or <a href="https://insomnia.rest/" rel="nofollow">Insomnia</a> for testing your API endpoints before integrating them into your code.</li>
</ul>
</li>
<li>
<p><strong>Logging:</strong></p>
<ul>
<li>Implement logging to monitor the behavior of your applications, which is crucial for debugging and maintaining your systems.</li>
</ul>
</li>
</ol>
<hr>
<p><a href="/docs/">Return to Documentation</a></p>
</article>
</body>
</html>